Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/fips.md`:
- Line 43: The documented gsutil command is missing the required permission
suffix on the principal; update the line containing "gsutil defacl ch -u
PLACEHOLDER gs://bosh-core-stemcells-fips" to include a permission suffix (for
example ":READER" or ":OWNER") on PLACEHOLDER (e.g., "PLACEHOLDER:READER") so
the command uses the correct principal format and will succeed when run.

In `@docs/new_stemcell_line.md`:
- Around line 11-35: The step "Add, commit, and push the new branch" (the line
with git push --set-upstream origin HEAD) must be moved so it occurs after the
documented edits to ci/pipelines/vars.yml, the update of STEMCELL_LINE in
ci/configure.sh, and after running ./ci/configure.sh; reorder the numbered steps
so editing ci/pipelines/vars.yml, updating STEMCELL_LINE="ubuntu-${short_name}"
in ci/configure.sh and running ./ci/configure.sh come before the add/commit/push
step to keep the workflow consistent.
- Line 8: Remove the stray trailing backtick in the branch creation command
string "git switch -c ubuntu-${short_name} {commit}`" so the line reads without
the backtick; update the command in the docs/new_stemcell_line.md to "git switch
-c ubuntu-${short_name} {commit}" ensuring no extra punctuation remains that
would break copy-paste execution.

In `@docs/publish.md`:
- Around line 11-13: The docs text references the wrong job name; replace the
string "aggregate-candidate-stemcells-1.x" with the actual builder pipeline job
name "aggregate-candidate-stemcells" in the publish.md content so the doc points
to the real job; search for the literal "aggregate-candidate-stemcells-1.x" in
the file and update that occurrence (preserve surrounding sentence and wording).

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/fips.md`:
- Around line 11-31: Add the required blank lines around the fenced YAML block
and the subsequent headings to satisfy markdownlint rules (MD031/MD022): insert
an empty line before the opening ```yaml fence and after the closing ``` fence,
and ensure there is a blank line between the fenced block and the "## setup
access" heading and between "## setup access" and "### working group actions"
(and similarly before "#### bucket owner actions") so the YAML code block and
each heading are separated by one blank line.

In `@docs/publish.md`:
- Around line 1-2: The markdown headings "# Publish a stemcell." and "## Verify
stemcell builds" need blank lines before and after each heading to comply with
Markdown formatting; update the document so there is an empty line above "#
Publish a stemcell." (if not at top) and an empty line below it, and likewise
ensure a blank line above and below "## Verify stemcell builds" to improve
readability and tool compatibility.
- Around line 17-18: The markdown heading "## Publish stemcells" lacks a blank
line after it; insert a single empty line immediately following the "## Publish
stemcells" heading in docs/publish.md so the heading is separated from the next
paragraph/content and renders correctly.

---

Duplicate comments:
In `@docs/fips.md`:
- Line 43: The example `gsutil defacl ch -u PLACEHOLDER
gs://bosh-core-stemcells-fips` is missing a permission suffix for the principal;
update the example so the `-u` argument uses the required principal:PERMISSION
form (e.g., replace PLACEHOLDER with a principal followed by a permission such
as :READER or :OWNER) so the command demonstrates the correct grant syntax.

In `@docs/publish.md`:
- Around line 11-13: Update the documentation line that references the job name
to use the actual builder pipeline job name "aggregate-candidate-stemcells"
instead of the version-suffixed example "aggregate-candidate-stemcells-1.x";
locate the sentence containing that parenthetical and replace the parenthetical
with the correct job name so the text reads that you should check the latest
build of the aggregate-candidate-stemcells job (no version suffix).

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/fips.md`:
- Line 44: Change the compound adjective "cross project" to "cross-project"
where it modifies "cloud buckets" (i.e., replace occurrences of 'cross project
cloud buckets' with 'cross-project cloud buckets') so the phrase is properly
hyphenated; search for the exact phrase "cross project cloud buckets" in the
document and update it to "cross-project cloud buckets".
- Around line 20-21: Update the credential variable names in the docs sample so
they match the pipeline credential names: replace the values currently shown as
"hmac-access_key" and "hmac-secret_key" for the keys access_key and secret_key
with "hmac_accesskey" and "hmac_secret" respectively; ensure the documentation
example uses access_key: hmac_accesskey and secret_key: hmac_secret to match the
pipeline configuration references.

In `@docs/new_stemcell_line.md`:
- Around line 20-24: The docs use the placeholder
STEMCELL_LINE="ubuntu-${short_name}" which can be unclear; update the example to
show both the template and a concrete example by appending a clarifying comment
or secondary line showing an actual expanded value (e.g.,
STEMCELL_LINE="ubuntu-jammy") so readers see both STEMCELL_LINE and short_name
usage; modify the snippet around the STEMCELL_LINE assignment (referencing the
STEMCELL_LINE variable and short_name export) to include the illustrative
example.
- Around line 11-18: The docs currently show adding an `oss:` list but the
pipeline expects a `stemcell_details:` object; update the example YAML in
docs/new_stemcell_line.md to demonstrate adding a `stemcell_details:` mapping
with keys used by the pipeline (e.g., branch, major_version, os_version,
os_name, os_short_name, etc.) so it matches what `ci/pipelines/vars.yml` and
`ci/pipelines/builder.yml` read via `data.values.stemcell_details`; ensure the
example uses the same field names and structure as the real vars.yml.

In `@docs/publish.md`:
- Around line 5-7: Update the sentence in docs/publish.md that reads "The
following CI build groups processes USN(s), and post a message to the
`#bosh-private` channel..." by fixing the verb agreement: change "processes" to
"process" so the clause reads "The following CI build groups process USN(s), and
post a message..." (leave "post" unchanged) to match the plural subject
"groups."
- Around line 38-43: Rewrite the ambiguous sentence that currently reads
"publish the GitHub release" so it clearly distinguishes it from the subsequent
"Finalize the draft release on GitHub" step: update the text around the phrases
"publish the GitHub release" and "Finalize the draft release on GitHub" to
indicate the correct sequence (for example, change "publish the GitHub release"
to "prepare the GitHub release draft" or "create the draft release" if
finalization/publishing happens after the Generate release notes step), and
ensure the following bullet about selecting `Previous Tag` explicitly states
this occurs during the finalization step.